ejson-kms (AWS)

2022-08-22 · 2 min read

A utility for managing a collection of secrets in source control using AWS KMS.

The secrets are encrypted using secret-key cryptography (NaCl Secretbox: XSalsa20 + Poly1305), using key wrapping with a master key stored on HSM-backed storage at AWS. Encrypted secrets are stored in a JSON file that can easily be shared and versioned.

secret encryption #

  • For each secret, a data key is requested from AWS KMS (see GenerateDataKey).
  • The encryption context is sent along and is stored alongside the encrypted data key. The name of the secret is added to the context automatically under the key Secret
  • KMS returns the data key encrypted with the master key (stored on AWS servers) and the corresponding plaintext.
  • That data key is used to encrypt one secret.
  • A random nonce is generated and NaCL Secretbox is used for encryption.
  • Under the hood, Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages. The length of messages is not hidden.
  • Finally, the encrypted data key, the random nonce and the encrypted secret are each stored in the JSON file.

secret decryption #

  • For each secret, the encrypted data key, random nonce and encrypted secret are extracted from the JSON file.
  • A request is made to AWS KMS to decrypt the encrypted data key (see Decrypt).
  • At this stage the encryption context is authenticated and logged. The name of the secret is added to the context automatically under the key Secret
  • Using the key plaintext and random nonce, the secret is decrypted using NaCL Secretbox.